/* -*- C++ -*- */

// ========================================================================
// $Id$
//
// = FILENAME
//   CosTrading.idl
//
// = DESCRIPTION
//   Trader  Service v1.0 described in CORBAservices: Common Object
//   Services Specification, chapter 16 OMG IDL for Trading Function
//   Module, p 16-74
//
// ========================================================================

#ifndef TAO_TRADING_IDL
#define TAO_TRADING_IDL

#include "tao/StringSeq.pidl"

#pragma prefix "omg.org"

module CosTrading
{
  // forward references to our interfaces

  interface Lookup;
  interface Register;
  interface Link;
  interface Proxy;
  interface Admin;
  interface OfferIterator;
  interface OfferIdIterator;

  // type definitions used in more than one interface
  typedef string Istring;
  typedef Object TypeRepository;

  typedef Istring PropertyName;
  typedef sequence<PropertyName> PropertyNameSeq;
  typedef any PropertyValue;

  struct Property
  {
    PropertyName name;
    PropertyValue value;
  };
  typedef sequence<Property> PropertySeq;

  struct Offer
  {
    Object reference;
    PropertySeq properties;
  };
  typedef sequence<Offer> OfferSeq;

  typedef string OfferId;
  typedef sequence<OfferId> OfferIdSeq;

  typedef Istring ServiceTypeName;  // similar structure to IR::Identifier

  typedef Istring Constraint;

  enum FollowOption
  {
    local_only,
    if_no_local,
    always
  };

  typedef Istring LinkName;
  typedef sequence<LinkName> LinkNameSeq;
  typedef LinkNameSeq TraderName;

  typedef string PolicyName;  // policy names restricted to Latin1
  typedef sequence<PolicyName> PolicyNameSeq;
  typedef any PolicyValue;

  struct Policy
  {
    PolicyName name;
    PolicyValue value;
  };
  typedef sequence<Policy> PolicySeq;

  // exceptions used in more than one interface

  exception UnknownMaxLeft {};

  exception NotImplemented {};

  exception IllegalServiceType
    {
      ServiceTypeName type;
    };

  exception UnknownServiceType
    {
      ServiceTypeName type;
    };

   exception IllegalPropertyName
     {
       PropertyName name;
     };

   exception DuplicatePropertyName
     {
       PropertyName name;
     };

   exception PropertyTypeMismatch
     {
       ServiceTypeName type;
       Property prop;
     };

   exception MissingMandatoryProperty
     {
       ServiceTypeName type;
       PropertyName name;
     };

   exception ReadonlyDynamicProperty
     {
       ServiceTypeName type;
       PropertyName name;
     };

   exception IllegalConstraint
     {
       Constraint constr;
     };

   exception InvalidLookupRef
     {
       Lookup target;
     };

   exception IllegalOfferId
     {
       OfferId id;
     };

   exception UnknownOfferId
     {
       OfferId id;
     };

   exception DuplicatePolicyName
     {
       PolicyName name;
     };

     // the interfaces

   interface TraderComponents
     {
       readonly attribute Lookup lookup_if;
       readonly attribute Register register_if;
       readonly attribute Link link_if;
       readonly attribute Proxy proxy_if;
       readonly attribute Admin admin_if;
     };

   interface SupportAttributes
     {
       readonly attribute boolean supports_modifiable_properties;
       readonly attribute boolean supports_dynamic_properties;
       readonly attribute boolean supports_proxy_offers;
       readonly attribute TypeRepository type_repos;
     };

   interface ImportAttributes
     {
       readonly attribute unsigned long def_search_card;
       readonly attribute unsigned long max_search_card;
       readonly attribute unsigned long def_match_card;
       readonly attribute unsigned long max_match_card;
       readonly attribute unsigned long def_return_card;
       readonly attribute unsigned long max_return_card;
       readonly attribute unsigned long max_list;
       readonly attribute unsigned long def_hop_count;
       readonly attribute unsigned long max_hop_count;
       readonly attribute FollowOption def_follow_policy;
       readonly attribute FollowOption max_follow_policy;
     };

   interface LinkAttributes
     {
       readonly attribute FollowOption max_link_follow_policy;
     };

   interface Lookup:TraderComponents,SupportAttributes,ImportAttributes
     {
       typedef Istring Preference;

       enum HowManyProps { none, some, all };

       union SpecifiedProps switch ( HowManyProps )
         {
         case some: PropertyNameSeq prop_names;
         };
       
       exception IllegalPreference {
         Preference pref;
       };
       
       exception IllegalPolicyName {
         PolicyName name;
       };
       
       exception PolicyTypeMismatch {
         Policy the_policy;
       };
       
       exception InvalidPolicyValue {
         Policy the_policy;
       };
       
       void query (in ServiceTypeName type,
                   in Constraint constr,
                   in Preference pref,
                   in PolicySeq policies,
                   in SpecifiedProps desired_props,
                   in unsigned long how_many,
                   out OfferSeq offers,
                   out OfferIterator offer_itr,
                   out PolicyNameSeq limits_applied)
         raises (IllegalServiceType,
                 UnknownServiceType,
                 IllegalConstraint,
                 IllegalPreference,
                 IllegalPolicyName,
                 PolicyTypeMismatch,
                 InvalidPolicyValue,
                 IllegalPropertyName,
                 DuplicatePropertyName,
                 DuplicatePolicyName);
     };
     
     interface Register : TraderComponents, SupportAttributes
       {                
         struct OfferInfo
         {
           Object reference;
           ServiceTypeName type;
           PropertySeq properties;
         };

         exception InvalidObjectRef {
           Object ref;
         };
         
         exception UnknownPropertyName {
           PropertyName name;
         };
         
         exception InterfaceTypeMismatch {
           ServiceTypeName type;
           Object reference;
         };
         
         exception ProxyOfferId {
           OfferId id;
         };
         
         exception MandatoryProperty {
           ServiceTypeName type;
           PropertyName name;
         };
         
         exception ReadonlyProperty {
           ServiceTypeName type;
           PropertyName name;
         };
         
         exception NoMatchingOffers {
           Constraint constr;
         };
         
         exception IllegalTraderName {
           TraderName name;
         };
         
         exception UnknownTraderName {
           TraderName name;
         };
         
         exception RegisterNotSupported {
           TraderName name;
         };

         OfferId export (in Object reference,
                         in ServiceTypeName type,
                         in PropertySeq properties)
           raises (InvalidObjectRef,
                   IllegalServiceType,
                   UnknownServiceType,
                   InterfaceTypeMismatch,
                   IllegalPropertyName, // e.g. prop_name = "<foo-bar"
                   PropertyTypeMismatch,
                   ReadonlyDynamicProperty,
                   MissingMandatoryProperty,
                   DuplicatePropertyName);

         void withdraw (in OfferId id)
           raises (IllegalOfferId,
                   UnknownOfferId,
                   ProxyOfferId);
         
         OfferInfo describe (in OfferId id)
           raises (IllegalOfferId,
                   UnknownOfferId,
                   ProxyOfferId);

         void modify (in OfferId id,
                      in PropertyNameSeq del_list,
                      in PropertySeq modify_list)
           raises (NotImplemented,
                   IllegalOfferId,
                   UnknownOfferId,
                   ProxyOfferId,
                   IllegalPropertyName,
                   UnknownPropertyName,
                   PropertyTypeMismatch,
                   ReadonlyDynamicProperty,
                   MandatoryProperty,
                   ReadonlyProperty,
                   DuplicatePropertyName);

         void withdraw_using_constraint (in ServiceTypeName type,
                                         in Constraint constr)
           raises (IllegalServiceType,
                   UnknownServiceType,
                   IllegalConstraint,
                   NoMatchingOffers);

         Register resolve (in TraderName name)
           raises (IllegalTraderName,
                   UnknownTraderName,
                   RegisterNotSupported);
       };

	interface Link : TraderComponents, SupportAttributes, LinkAttributes
          {
		struct LinkInfo
                {
                  Lookup target;
                  Register target_reg;
                  FollowOption def_pass_on_follow_rule;
                  FollowOption limiting_follow_rule;
		};

		exception IllegalLinkName {
                  LinkName name;
		};
                
		exception UnknownLinkName {
                  LinkName name;
		};
                
		exception DuplicateLinkName {
                  LinkName name;
		};
                
		exception DefaultFollowTooPermissive {
                  FollowOption def_pass_on_follow_rule;
                  FollowOption limiting_follow_rule;
		};
                
		exception LimitingFollowTooPermissive {
                  FollowOption limiting_follow_rule;
                  FollowOption max_link_follow_policy;
		};
                
		void add_link (in LinkName name,
                               in Lookup target,
                               in FollowOption def_pass_on_follow_rule,
                               in FollowOption limiting_follow_rule)
                  raises (IllegalLinkName,
                          DuplicateLinkName,
                          InvalidLookupRef, // e.g. nil
                          DefaultFollowTooPermissive,
                          LimitingFollowTooPermissive);

		void remove_link (in LinkName name)
                  raises (IllegalLinkName,
                          UnknownLinkName);

		LinkInfo describe_link (in LinkName name)
                  raises (IllegalLinkName,
                          UnknownLinkName);

		LinkNameSeq list_links ( );

		void modify_link (in LinkName name,
                                  in FollowOption def_pass_on_follow_rule,
                                  in FollowOption limiting_follow_rule)
                  raises (IllegalLinkName,
                          UnknownLinkName,
                          DefaultFollowTooPermissive,
                          LimitingFollowTooPermissive);
	};

	interface Proxy : TraderComponents, SupportAttributes
          {
            typedef Istring ConstraintRecipe;
            
            struct ProxyInfo
            {
              ServiceTypeName type;
              Lookup target;
              PropertySeq properties;
              boolean if_match_all;
              ConstraintRecipe recipe;
              PolicySeq policies_to_pass_on;
            };

            exception IllegalRecipe {
              ConstraintRecipe recipe;
            };
            
            exception NotProxyOfferId {
              OfferId id;
            };
            
            OfferId export_proxy (in Lookup target,
                                  in ServiceTypeName type,
                                  in PropertySeq properties,
                                  in boolean if_match_all,
                                  in ConstraintRecipe recipe,
                                  in PolicySeq policies_to_pass_on)
              raises (IllegalServiceType,
                      UnknownServiceType,
                      InvalidLookupRef, // e.g. nil
                      IllegalPropertyName,
                      PropertyTypeMismatch,
                      ReadonlyDynamicProperty,
                      MissingMandatoryProperty,
                      IllegalRecipe,
                      DuplicatePropertyName,
                      DuplicatePolicyName);

            void withdraw_proxy (in OfferId id)
              raises (IllegalOfferId,
                      UnknownOfferId,
                      NotProxyOfferId);
            
            ProxyInfo describe_proxy (in OfferId id)
              raises (IllegalOfferId,
                      UnknownOfferId,
                      NotProxyOfferId);
          };
          
          interface Admin : TraderComponents, SupportAttributes, ImportAttributes, LinkAttributes
            {              
              typedef sequence<octet> OctetSeq;
              
              readonly attribute OctetSeq request_id_stem;
              
              unsigned long set_def_search_card (in unsigned long value);
              unsigned long set_max_search_card (in unsigned long value);
              
              unsigned long set_def_match_card (in unsigned long value);
              unsigned long set_max_match_card (in unsigned long value);
              
              unsigned long set_def_return_card (in unsigned long value);
              unsigned long set_max_return_card (in unsigned long value);
              
              unsigned long set_max_list (in unsigned long value);
              
              boolean set_supports_modifiable_properties (in boolean value);
              boolean set_supports_dynamic_properties (in boolean value);
              boolean set_supports_proxy_offers (in boolean value);
              
              unsigned long set_def_hop_count (in unsigned long value);
              unsigned long set_max_hop_count (in unsigned long value);
              
              FollowOption set_def_follow_policy (in FollowOption policy);
              FollowOption set_max_follow_policy (in FollowOption policy);
              
              FollowOption set_max_link_follow_policy (in FollowOption policy);
              
              TypeRepository set_type_repos (in TypeRepository repository);
              
              OctetSeq set_request_id_stem (in OctetSeq stem);
              
              void list_offers (in unsigned long how_many,
                                out OfferIdSeq ids,
                                out OfferIdIterator id_itr)
                raises (NotImplemented);

              void list_proxies (in unsigned long how_many,
                                 out OfferIdSeq ids,
                                 out OfferIdIterator id_itr)
                raises (NotImplemented);
	};

	interface OfferIterator
          {
		unsigned long max_left ()
                  raises (UnknownMaxLeft);

		boolean next_n (in unsigned long n,
                                out OfferSeq offers);

		void destroy ();
	};

	interface OfferIdIterator
          {
            unsigned long max_left ()
              raises (UnknownMaxLeft);
            
            boolean next_n (in unsigned long n,
                            out OfferIdSeq ids);

            void destroy ();
          };
          
}; /* end module CosTrading */

#endif /* TAO_TRADING_IDL */
